home *** CD-ROM | disk | FTP | other *** search
/ Aminet 40 / Aminet 40 (2000)(Schatztruhe)[!][Dec 2000].iso / Aminet / dev / c / ExtrasLib.lha / ExtrasLib / Source / PackData.doc < prev    next >
Encoding:
Text File  |  2000-09-30  |  4.7 KB  |  156 lines
  1. #include <extras/packdata.h>
  2.  
  3. /****** extras.lib/PD_PackData ******************************************
  4. *
  5. *   NAME
  6. *       PD_PackData -- Pack supplied data into a memory block.
  7. *
  8. *   SYNOPSIS
  9. *       packeddata = PD_PackData(Tags)
  10. *
  11. *       struct PackedData *PD_PackData(Tag Tags, ... )
  12. *
  13. *   FUNCTION
  14. *       Packs supplied data into a memory block, suitable for writing
  15. *       to disk.
  16. *
  17. *   INPUTS
  18. *       Tags - a TagList.
  19. *           PD_Version - Adds a ULONG into the memory block.
  20. *                 Sets the version of the data.
  21. *
  22. *           PD_BYTE - Adds a BYTE into the memory block.
  23. *           PD_UBYTE - Adds a UBYTE into the memory block.
  24. *
  25. *           PD_WORD - Adds a WORD into the memory block. 
  26. *           PD_UWORD - Adds a UWORD into the memory block.
  27. *
  28. *           PD_LONG - Adds a LONG into the memory block.
  29. *           PD_ULONG - Adds a ULONG into the memory block.
  30. *
  31. *           PD_STRPTR - Adds a NULL terminated string into the memory block.
  32. *                 NULL pointers are supported
  33. *
  34. *           PD_APTRSize - Adds the ULONG into the memory block,
  35. *                 Sets size for subsequent PD_APTRs.
  36. *           PD_APTR - Adds data into the memory block.  Size 
  37. *                 of data is set by previous PD_APTRSize.
  38. *                 if NULL, PD_APtrSize bytes are still written but are
  39. *                 unset.
  40. *
  41. *           PD_BufferSize - Set the size of subsequent PD_Buffers
  42. *                 This tag does not add data to buffer.
  43. *
  44. *           PD_Buffer     - Adds size of buffer, ULONG, followed by
  45. *                 data pointed to by ti_Data. 
  46. *                 See note for PD_UnpackData(()
  47. *           
  48. *           PD_MemoryFlags - Sets MemoryFlags for allocating 
  49. *
  50. *
  51. *   RESULT
  52. *
  53. *   EXAMPLE
  54. *
  55. *   NOTES
  56. *     Except for BYTEs, data is UWORD aligned, pads are inserted as needed.
  57. *
  58. *     PackedData->pd_Data
  59. *     {
  60. *       ULONG privatelength
  61. *       {private bytes}
  62. *       user data
  63. *     }     
  64. *
  65. *
  66. *   BUGS
  67. *
  68. *   SEE ALSO
  69. *
  70. ******************************************************************************
  71. *
  72. */
  73.  
  74. /****** extras.lib/PD_UnpackData ******************************************
  75. *
  76. *   NAME
  77. *       PD_UnpackData -- Unpack memory block.
  78. *
  79. *   SYNOPSIS
  80. *       success = PD_UnpackData(Tags)
  81. *
  82. *       BOOL *PD_UnpackData(Tag Tags, ... )
  83. *
  84. *   FUNCTION
  85. *       Packs supplied data into a memory block, suitable for writing
  86. *       to disk.
  87. *
  88. *   INPUTS
  89. *       Tags - a TagList.
  90. *           For most tags, ti_Data is a storage pointer, if NULL the 
  91. *           data is parsed but not stored.
  92. *
  93. *           PD_Version   - (ULONG *) Reads the version of the data.
  94. *
  95. *           PD_IfVersion - (ULONG) Once PD_Version has been read, you can
  96. *               this tag to stop data processing if PD_Version is lower than
  97. *               the value of this tag. 
  98. *
  99. *           PD_BYTE - (BYTE *) Read a BYTE
  100. *           PD_UBYTE -(UBYTE *)
  101. *
  102. *           PD_WORD - (WORD *) Read a WORD
  103. *           PD_UWORD -(UWORD *)
  104. *
  105. *           PD_LONG - (LONG *) Read a LONG
  106. *           PD_ULONG -(LONG *)
  107. *
  108. *           PD_STRPTR - (STRPTR *) AllocVec()s Memory for new STRPTR
  109. *               if PD_FreeSTRPTR is set, existing STRPTR is FreeVec()ed.
  110. *
  111. *           PD_APTRSize - (ULONG *) Reads the amount of bytes that subsequent
  112. *               PD_APTRs read from the packed data.
  113. *
  114. *           PD_APTR - Reads data from the memory block.  Size 
  115. *                 of data is set by previous PD_APTRSize.
  116. *                 if NULL, PD_APtrSize bytes are still written but are
  117. *                 unset.
  118. *
  119. *           PD_BufferSize - (ULONG) Set data size for subsequent PD_Struct 
  120. *                 reads. This tag does not read any data, you must specify 
  121. *                 the size of your Buffer.
  122. *
  123. *           PD_Buffer - (APTR) Data is copied to existing memory, the amount 
  124. *                 of data copied will be the lesser of PD_BufferSize or the
  125. *                 size stored in the packed data block.
  126. *           
  127. *           PD_MemoryFlags - Sets MemoryFlags for allocating 
  128. *
  129. *
  130. *   RESULT
  131. *
  132. *   EXAMPLE
  133. *       PD_UnpackData(pd,
  134. *           PD_Version,     &dataversion, // store version number
  135. *           PD_BYTE,        &byte1,
  136. *           PD_BYTE,        0,            // byte not stored.
  137. *           PD_STRPTR,      &string,
  138. *
  139. *           PD_IfVersion,   1, /* the following will only be read id PD_Version >= 1 */
  140. *           PD_APTRSize,    10,
  141. *           PD_APTR,        &memchunk1,
  142. *           PD_APTR,        &memchunk2,
  143. *      
  144. *           PD_IfVersion,   2, /* the following will only be read id PD_Version >= 2 */
  145. *           PD_STRUCT(mystruct),
  146. *      
  147. *           TAG_DONE,       0))
  148. *
  149. *   BUGS
  150. *
  151. *   SEE ALSO
  152. *
  153. ******************************************************************************
  154. *
  155. */
  156.